<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>&lt;GIOChannel&gt;: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re21.html" title="&lt;%GLibHookFlagMask&gt;">
<link rel="next" href="re23.html" title="&lt;%GLibIOChannelError&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re21.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re23.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.23"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GIOChannel&gt;</h2>
<p>&lt;GIOChannel&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.23.2"></a><h2>Description</h2>
<p>A data structure representing an IO Channel. The fields should be
considered private and should only be accessed with the following
functions.</p>
</div>
<div class="refsect1">
<a name="id-1.1.23.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.23.3.2"></a><h3>close</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (iochannel:close self))
</pre></div>
<p>Close an IO channel. Any pending data to be written will be
flushed, ignoring errors. The channel will not be freed until the
last reference is dropped using <code class="function">g_io_channel_unref()</code>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.2.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>A <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.3"></a><h3>flush</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:flush self))
</pre></div>
<p>Flushes the write buffer for the GIOChannel.</p>
<div class="refsect3">
<a name="id-1.1.23.3.3.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.4"></a><h3>get-buffer-condition</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:get-buffer-condition self))
</pre></div>
<p>This function returns a <span class="type">GIOCondition</span> depending on whether there
is data to be read/space to write data in the internal buffers in
the <span class="type">GIOChannel</span>. Only the flags <code class="constant">G_IO_IN</code> and <code class="constant">G_IO_OUT</code> may be set.</p>
<div class="refsect3">
<a name="id-1.1.23.3.4.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>A <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.5"></a><h3>get-buffer-size</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:get-buffer-size self))
</pre></div>
<p>Gets the buffer size.</p>
<div class="refsect3">
<a name="id-1.1.23.3.5.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.6"></a><h3>get-buffered?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:get-buffered? self))
</pre></div>
<p>Returns whether <em class="parameter"><code>channel</code></em> is buffered.</p>
<div class="refsect3">
<a name="id-1.1.23.3.6.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.7"></a><h3>get-close-on-unref?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:get-close-on-unref? self))
</pre></div>
<p>Returns whether the file/socket/whatever associated with <em class="parameter"><code>channel</code></em>
will be closed when <em class="parameter"><code>channel</code></em> receives its final unref and is
destroyed. The default value of this is <code class="constant">TRUE</code> for channels created
by g_io_channel_new_file (), and <code class="constant">FALSE</code> for all other channels.</p>
<div class="refsect3">
<a name="id-1.1.23.3.7.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span>.</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.8"></a><h3>get-encoding</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:get-encoding self))
</pre></div>
<p>Gets the encoding for the input/output of the channel.
The internal encoding is always UTF-8. The encoding <code class="constant">NULL</code>
makes the channel safe for binary data.</p>
<div class="refsect3">
<a name="id-1.1.23.3.8.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.9"></a><h3>get-flags</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:get-flags self))
</pre></div>
<p>Gets the current flags for a <span class="type">GIOChannel</span>, including read-only
flags such as <code class="constant">G_IO_FLAG_IS_READABLE</code>.
</p>
<p>The values of the flags <code class="constant">G_IO_FLAG_IS_READABLE</code> and <code class="constant">G_IO_FLAG_IS_WRITABLE</code>
are cached for internal use by the channel when it is created.
If they should change at some later point (e.g. partial shutdown
of a socket with the UNIX <code class="function">shutdown()</code> function), the user
should immediately call <code class="function">g_io_channel_get_flags()</code> to update
the internal values of these flags.</p>
<div class="refsect3">
<a name="id-1.1.23.3.9.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.10"></a><h3>get-line-term</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:get-line-term self length))
</pre></div>
<p>This returns the string that <span class="type">GIOChannel</span> uses to determine
where in the file a line break occurs. A value of <code class="constant">NULL</code>
indicates autodetection.</p>
<div class="refsect3">
<a name="id-1.1.23.3.10.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>a location to return the length of the line terminator</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.11"></a><h3>init</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (iochannel:init self))
</pre></div>
<p>Initializes a <span class="type">GIOChannel</span> struct.
</p>
<p>This is called by each of the above functions when creating a
<span class="type">GIOChannel</span>, and so is not often needed by the application
programmer (unless you are creating a new type of <span class="type">GIOChannel</span>).</p>
<div class="refsect3">
<a name="id-1.1.23.3.11.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.12"></a><h3>read</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:read self buf count bytes-read))
</pre></div>
<p>Reads data from a <span class="type">GIOChannel</span>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.12.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buf</p></td>
<td class="parameter_description">
<p>a buffer to read the data into (which should be at least
      count bytes long)</p>
<p>Passed as <code class="code">buf</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>count</p></td>
<td class="parameter_description">
<p>the number of bytes to read from the <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">count</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>returns the number of bytes actually read</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.13"></a><h3>read-chars!</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return buf bytes-read) (iochannel:read-chars! self buf))
</pre></div>
<p>Replacement for <code class="function">g_io_channel_read()</code> with the new API.</p>
<div class="refsect3">
<a name="id-1.1.23.3.13.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buf</p></td>
<td class="parameter_description">
<p>
    </p>
<p>a buffer to read data into</p>
<p>Passed as <code class="code">buf</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>count</p></td>
<td class="parameter_description">
<p>the size of the buffer. Note that the buffer may not be
    completely filled even if there is data in the buffer if the
    remaining data is not a complete character.</p>
<p>Inferred from <code class="code">buf</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_read</p></td>
<td class="parameter_description">
<p>The number of bytes read. This may be
    zero even on success if count &lt; 6 and the channel's encoding
    is non-<code class="constant">NULL</code>. This indicates that the next UTF-8 character is
    too wide for the buffer.</p>
<p>Passed as <code class="code">bytes-read</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.14"></a><h3>read-line</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return str-return length terminator-pos)
  (iochannel:read-line self))
</pre></div>
<p>Reads a line, including the terminating character(s),
from a <span class="type">GIOChannel</span> into a newly-allocated string.
<em class="parameter"><code>str_return</code></em> will contain allocated memory if the return
is <code class="constant">G_IO_STATUS_NORMAL</code>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.14.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str_return</p></td>
<td class="parameter_description">
<p>The line read from the <span class="type">GIOChannel</span>, including the
             line terminator. This data should be freed with <code class="function">g_free()</code>
             when no longer needed. This is a nul-terminated string.
             If a <em class="parameter"><code>length</code></em> of zero is returned, this will be <code class="constant">NULL</code> instead.</p>
<p>Passed as <code class="code">str-return</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>location to store length of the read data, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>terminator_pos</p></td>
<td class="parameter_description">
<p>location to store position of line terminator, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">terminator-pos</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.15"></a><h3>read-line-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (iochannel:read-line-string self buffer terminator-pos))
</pre></div>
<p>Reads a line from a <span class="type">GIOChannel</span>, using a <span class="type">GString</span> as a buffer.</p>
<div class="refsect3">
<a name="id-1.1.23.3.15.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buffer</p></td>
<td class="parameter_description">
<p>a <span class="type">GString</span> into which the line will be written.
         If <em class="parameter"><code>buffer</code></em> already contains data, the old data will
         be overwritten.</p>
<p>Passed as <code class="code">buffer</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>terminator_pos</p></td>
<td class="parameter_description">
<p>location to store position of line terminator, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">terminator-pos</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.16"></a><h3>read-to-end</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return str-return length) (iochannel:read-to-end self))
</pre></div>
<p>Reads all the remaining data from the file.</p>
<div class="refsect3">
<a name="id-1.1.23.3.16.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>str_return</p></td>
<td class="parameter_description">
<p>Location to
             store a pointer to a string holding the remaining data in the
             <span class="type">GIOChannel</span>. This data should be freed with <code class="function">g_free()</code> when no
             longer needed. This data is terminated by an extra nul
             character, but there may be other nuls in the intervening data.</p>
<p>Passed as <code class="code">str-return</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>location to store length of the data</p>
<p>Inferred from <code class="code">str-return</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.17"></a><h3>read-unichar</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return thechar) (iochannel:read-unichar self))
</pre></div>
<p>Reads a Unicode character from <em class="parameter"><code>channel</code></em>.
This function cannot be called on a channel with <code class="constant">NULL</code> encoding.</p>
<div class="refsect3">
<a name="id-1.1.23.3.17.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>thechar</p></td>
<td class="parameter_description">
<p>a location to return a character</p>
<p>Passed as <code class="code">thechar</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.18"></a><h3>ref</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:ref self))
</pre></div>
<p>Increments the reference count of a <span class="type">GIOChannel</span>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.18.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.19"></a><h3>seek</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:seek self offset type))
</pre></div>
<p>Sets the current position in the <span class="type">GIOChannel</span>, similar to the standard
library function <code class="function">fseek()</code>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.19.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>offset</p></td>
<td class="parameter_description">
<p>an offset, in bytes, which is added to the position specified
         by <em class="parameter"><code>type</code></em></p>
<p>Passed as <code class="code">offset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>type</p></td>
<td class="parameter_description">
<p>the position in the file, which can be <code class="constant">G_SEEK_CUR</code> (the current
       position), <code class="constant">G_SEEK_SET</code> (the start of the file), or <code class="constant">G_SEEK_END</code>
       (the end of the file)</p>
<p>Passed as <code class="code">type</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.20"></a><h3>seek-position</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:seek-position self offset type))
</pre></div>
<p>Replacement for <code class="function">g_io_channel_seek()</code> with the new API.</p>
<div class="refsect3">
<a name="id-1.1.23.3.20.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>offset</p></td>
<td class="parameter_description">
<p>The offset in bytes from the position specified by <em class="parameter"><code>type</code></em></p>
<p>Passed as <code class="code">offset</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>type</p></td>
<td class="parameter_description">
<p>a <span class="type">GSeekType</span>. The type <code class="constant">G_SEEK_CUR</code> is only allowed in those
                     cases where a call to g_io_channel_set_encoding ()
                     is allowed. See the documentation for
                     g_io_channel_set_encoding () for details.</p>
<p>Passed as <code class="code">type</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.21"></a><h3>set-buffer-size</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (iochannel:set-buffer-size self size))
</pre></div>
<p>Sets the buffer size.</p>
<div class="refsect3">
<a name="id-1.1.23.3.21.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>size</p></td>
<td class="parameter_description">
<p>the size of the buffer, or 0 to let GLib pick a good size</p>
<p>Passed as <code class="code">size</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.22"></a><h3>set-buffered</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (iochannel:set-buffered self buffered))
</pre></div>
<p>The buffering state can only be set if the channel's encoding
is <code class="constant">NULL</code>. For any other encoding, the channel must be buffered.
</p>
<p>A buffered channel can only be set unbuffered if the channel's
internal buffers have been flushed. Newly created channels or
channels which have returned <code class="constant">G_IO_STATUS_EOF</code>
not require such a flush. For write-only channels, a call to
g_io_channel_flush () is sufficient. For all other channels,
the buffers may be flushed by a call to g_io_channel_seek_position ().
This includes the possibility of seeking with seek type <code class="constant">G_SEEK_CUR</code>
and an offset of zero. Note that this means that socket-based
channels cannot be set unbuffered once they have had data
read from them.
</p>
<p>On unbuffered channels, it is safe to mix read and write
calls from the new and old APIs, if this is necessary for
maintaining old code.
</p>
<p>The default state of the channel is buffered.</p>
<div class="refsect3">
<a name="id-1.1.23.3.22.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buffered</p></td>
<td class="parameter_description">
<p>whether to set the channel buffered or unbuffered</p>
<p>Passed as <code class="code">buffered</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.23"></a><h3>set-close-on-unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (iochannel:set-close-on-unref self do-close))
</pre></div>
<p>Whether to close the channel on the final unref of the <span class="type">GIOChannel</span>
data structure. The default value of this is <code class="constant">TRUE</code> for channels
created by g_io_channel_new_file (), and <code class="constant">FALSE</code> for all other channels.
</p>
<p>Setting this flag to <code class="constant">TRUE</code> for a channel you have already closed
can cause problems when the final reference to the <span class="type">GIOChannel</span> is dropped.</p>
<div class="refsect3">
<a name="id-1.1.23.3.23.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>do_close</p></td>
<td class="parameter_description">
<p>Whether to close the channel on the final unref of
           the GIOChannel data structure.</p>
<p>Passed as <code class="code">do-close</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.24"></a><h3>set-encoding</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:set-encoding self encoding))
</pre></div>
<p>Sets the encoding for the input/output of the channel.
The internal encoding is always UTF-8. The default encoding
for the external file is UTF-8.
</p>
<p>The encoding <code class="constant">NULL</code> is safe to use with binary data.
</p>
<p>The encoding can only be set if one of the following conditions
is true:
</p>
<p>- The channel was just created, and has not been written to or read from yet.
</p>
<p>- The channel is write-only.
</p>
<p>- The channel is a file, and the file pointer was just repositioned
  by a call to <code class="function">g_io_channel_seek_position()</code>. (This flushes all the
  internal buffers.)
</p>
<p>- The current encoding is <code class="constant">NULL</code> or UTF-8.
</p>
<p>- One of the (new API) read functions has just returned <code class="constant">G_IO_STATUS_EOF</code>
  (or, in the case of <code class="function">g_io_channel_read_to_end()</code>, <code class="constant">G_IO_STATUS_NORMAL</code>).
</p>
<p>-  One of the functions <code class="function">g_io_channel_read_chars()</code> or
   <code class="function">g_io_channel_read_unichar()</code> has returned <code class="constant">G_IO_STATUS_AGAIN</code> or
   <code class="constant">G_IO_STATUS_ERROR</code>. This may be useful in the case of
   <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code>.
   Returning one of these statuses from <code class="function">g_io_channel_read_line()</code>,
   <code class="function">g_io_channel_read_line_string()</code>, or <code class="function">g_io_channel_read_to_end()</code>
   does not guarantee that the encoding can be changed.
</p>
<p>Channels which do not meet one of the above conditions cannot call
<code class="function">g_io_channel_seek_position()</code> with an offset of <code class="constant">G_SEEK_CUR</code>, and, if
they are "seekable", cannot call <code class="function">g_io_channel_write_chars()</code> after
calling one of the API "read" functions.</p>
<div class="refsect3">
<a name="id-1.1.23.3.24.13"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>encoding</p></td>
<td class="parameter_description">
<p>the encoding type</p>
<p>Passed as <code class="code">encoding</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.25"></a><h3>set-flags</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:set-flags self flags))
</pre></div>
<p>Sets the (writeable) flags in <em class="parameter"><code>channel</code></em> to (<em class="parameter"><code>flags</code></em> &amp; <code class="constant">G_IO_FLAG_SET_MASK</code>).</p>
<div class="refsect3">
<a name="id-1.1.23.3.25.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>the flags to set on the IO channel</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.26"></a><h3>set-line-term</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (iochannel:set-line-term self line-term length))
</pre></div>
<p>This sets the string that <span class="type">GIOChannel</span> uses to determine
where in the file a line break occurs.</p>
<div class="refsect3">
<a name="id-1.1.23.3.26.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>line_term</p></td>
<td class="parameter_description">
<p>The line termination string. Use <code class="constant">NULL</code> for
            autodetect.  Autodetection breaks on "\n", "\r\n", "\r", "\0",
            and the Unicode paragraph separator. Autodetection should not be
            used for anything other than file-based channels.</p>
<p>Passed as <code class="code">line-term</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>The length of the termination string. If -1 is passed, the
         string is assumed to be nul-terminated. This option allows
         termination strings with embedded nuls.</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.27"></a><h3>shutdown</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:shutdown self flush))
</pre></div>
<p>Close an IO channel. Any pending data to be written will be
flushed if <em class="parameter"><code>flush</code></em> is <code class="constant">TRUE</code>. The channel will not be freed until the
last reference is dropped using <code class="function">g_io_channel_unref()</code>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.27.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flush</p></td>
<td class="parameter_description">
<p>if <code class="constant">TRUE</code>, flush pending</p>
<p>Passed as <code class="code">flush</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.28"></a><h3>unix-get-fd</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:unix-get-fd self))
</pre></div>
<p>Returns the file descriptor of the <span class="type">GIOChannel</span>.
</p>
<p>On Windows this function returns the file descriptor or socket of
the <span class="type">GIOChannel</span>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.28.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span>, created with <code class="function">g_io_channel_unix_new()</code>.</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.29"></a><h3>unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (iochannel:unref self))
</pre></div>
<p>Decrements the reference count of a <span class="type">GIOChannel</span>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.29.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.30"></a><h3>write</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:write self buf count bytes-written))
</pre></div>
<p>Writes data to a <span class="type">GIOChannel</span>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.30.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buf</p></td>
<td class="parameter_description">
<p>the buffer containing the data to write</p>
<p>Passed as <code class="code">buf</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>count</p></td>
<td class="parameter_description">
<p>the number of bytes to write</p>
<p>Passed as <code class="code">count</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>the number of bytes actually written</p>
<p>Passed as <code class="code">bytes-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.31"></a><h3>write-chars</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return bytes-written) (iochannel:write-chars self buf count))
</pre></div>
<p>Replacement for <code class="function">g_io_channel_write()</code> with the new API.
</p>
<p>On seekable channels with encodings other than <code class="constant">NULL</code> or UTF-8, generic
mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
may only be made on a channel from which data has been read in the
cases described in the documentation for g_io_channel_set_encoding ().</p>
<div class="refsect3">
<a name="id-1.1.23.3.31.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>buf</p></td>
<td class="parameter_description">
<p>a buffer to write data from</p>
<p>Passed as <code class="code">buf</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>count</p></td>
<td class="parameter_description">
<p>the size of the buffer. If -1, the buffer
        is taken to be a nul-terminated string.</p>
<p>Passed as <code class="code">count</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>bytes_written</p></td>
<td class="parameter_description">
<p>The number of bytes written. This can be nonzero
                even if the return value is not <code class="constant">G_IO_STATUS_NORMAL</code>.
                If the return value is <code class="constant">G_IO_STATUS_NORMAL</code> and the
                channel is blocking, this will always be equal
                to <em class="parameter"><code>count</code></em> if <em class="parameter"><code>count</code></em> &gt;= 0.</p>
<p>Passed as <code class="code">bytes-written</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.32"></a><h3>write-unichar</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:write-unichar self thechar))
</pre></div>
<p>Writes a Unicode character to <em class="parameter"><code>channel</code></em>.
This function cannot be called on a channel with <code class="constant">NULL</code> encoding.</p>
<div class="refsect3">
<a name="id-1.1.23.3.32.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>channel</p></td>
<td class="parameter_description">
<p>a <span class="type">GIOChannel</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>thechar</p></td>
<td class="parameter_description">
<p>a character</p>
<p>Passed as <code class="code">thechar</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.33"></a><h3>iochannel:unix-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:unix-new fd))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.23.3.33.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>fd</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">fd</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.34"></a><h3>iochannel:new-file</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:new-file filename mode))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.23.3.34.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>filename</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">filename</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>mode</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">mode</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.35"></a><h3>iochannel:error-from-errno</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:error-from-errno en))
</pre></div>
<p>Converts an <code class="code">errno</code> error number to a <span class="type">GIOChannelError</span>.</p>
<div class="refsect3">
<a name="id-1.1.23.3.35.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>en</p></td>
<td class="parameter_description">
<p>an <code class="code">errno</code> error number, e.g. <code class="code">EINVAL</code></p>
<p>Passed as <code class="code">en</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.23.3.36"></a><h3>iochannel:error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (iochannel:error-quark))
</pre></div>
<p>Undocumented</p>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>
